Projet Zuul: Exercice 7.26.1

Forum des exercices du projet Zuul

Exercice 7.26.1

Vous êtes abonné à cette discussion. Cliquez pour vous désabonner.

Attention ! Ne pas passer cet exercice, sinon vous risquez de ne pas pouvoir résoudre les problèmes à temps pour rendre votre projet sur le serveur JNews avant la limite que vous vous serez fixée.

2 javadocs peuvent être utiles pour un même projet :

la 1^ère est la javadoc habituelle, destinée à l'utilisateur d'une classe ; il ne voit que ce qui est public
la 2^ème est la javadoc destinée au programmeur ; elle contient en plus tout ce qui est privé et donne accès au code source

a) Générer les 2 javadoc du projet en utilisant :
javadoc -d userdoc -author -version *.java
javadoc -d progdoc -author -version -private -linksource *.java
à partir de la ligne de commande (shell ou Terminal ou Invite de commandes).

Ces deux commandes sont valables sous Linux, Windows, MacOS, à condition d'être dans le répertoire où sont situés les fichiers .java du projet.
La commande javadoc n'est en général pas exécutable directement dans le cas particulier de Windows ou MacOS. Lire les échanges ci-dessous.

b) Pour maintenir à jour la page web de votre projet (si vous avez fait l'exercicce 7.0), recopiez les 2 répertoires au bon endroit sur votre compte et rendez ces documentations accessibles par un lien sur la page web du jeu.
Vous pouvez trouver les commandes de modification des droits d'accès à la fin de l'aide sur les commandes linux indiquée sur la page de l'unité Connaissances des Moyens Informatiques que vous avez suivie en début d'année scolaire.

c) En cas de problèmes avec les caractères accentués, il suffit de remplacer les 2 commandes du a) par celles données à la fin des échanges ci-dessous.

d) En cas de warning, vous pouvez les ignorer dans un premier temps (ça veut quand-même dire que votre javadoc est incomplète), mais en cas d'error, vous devez les corriger pour que la javadoc soit générée.
L'erreur la plus fréquente est un nom de paramètre qui ne correspond pas au nom dans votre code.

e) Pour vérifier que les javadocs ont bien été générées, il suffit de double-cliquer sur le fichier index.html qui se trouve dans chacun des répertoires userdoc et progdoc, puis de naviguer dans les différentes classes.

Je comprends que ces commandes sont à taper dans un terminal Linux.

Mais comment fait-on quand on n'a que Windows ?

Windows :

Réponse courte : exactement pareil ! (quand la préparation ci-dessous a été effectuée)

Précision : dans un terminal DOS (ou invite de commande, pas WPS)

Réponse longue : les commandes du JDK ne sont souvent pas accessibles à partir de la ligne de commande DOS ; il faut ajouter le bon chemin d'accès à la variable d'environnement PATH. Attention à respecter les espaces dans les commandes ci-dessous !

1) Déterminer le chemin d'accès d'installation du JDK :
- si vous le connaissez, passez directement à l'étape 2)
- en général, DIR "C:\Program Files\BlueJ\jdk\bin" doit montrer javac.exe, javadoc.exe, et plein d'autres commandes exécutables
- mais le chemin peut aussi ressembler à "C:\Program Files\Java\JDK....\bin" si vous avez installé le JDK indépendamment de BlueJ (les .... correspondent en général à la version du JDK)
Si vous ne trouvez pas le répertoire de BlueJ ou du JDK, vous pouvez taper à la racine : DIR/S bluej ou DIR/S jdk
Avant de passer au point 2), tapez DIR "C:\......\bin" et vérifiez qu'il y a bien le fichier javadoc.exe.

2) Taper la commande : SET PATH="C:\......\bin";%PATH%
en utilisant le chemin trouvé au point précédent, ce qui aura pour effet de rendre accessible notamment la commande javadoc
Pour vérifier que la commande précédente a bien fonctionné, vous pouvez taper la commande PATH et vous devez voir affiché au début le chemin d'accès que vous venez d'ajouter.
Pour vérifier que vous avez utilisé le bon chemin d'accès, vous pouvez taper la commande javadoc --version et vous ne devez plus voir affiché que cette commande n'est pas reconnue.

3) Pour ne pas avoir refaire cette manipulation à chaque fois qu'on rouvre la fenêtre DOS, il peut être agréable de créer un fichier de commande (par exemple, USEJAVA.BAT) qui contiendra la commande ci-dessus. Il suffira alors dès l'ouverture de la fenêtre DOS, de taper la commande USEJAVA (sous réserve que USEJAVA.BAT se trouve dans le répertoire courant).

4) Ensuite, ne pas oublier d'aller dans le répertoire (cd comme change directory) racine du projet (là où se trouve Game.java) avant de taper (copier/coller) les 2 commandes données dans l'énoncé.

La commande CD sous DOS (invite de commande Windows)

Si vous êtes sur le lecteur C: alors que votre projet est sur D:, il suffit de taper :
D:
Si vous êtes dans le bon lecteur, mais dans un répertoire très différent de celui de votre projet, il suffit de taper :
cd \
pour revenir à la racine du lecteur.
Si vous êtes dans la bonne branche de votre hiérarchie de fichiers, il suffit de taper :
cd Rep ou cd Rep\Sous
pour aller dans le répertoire Rep ou le sous-répertoire Sous du répertoire Rep.
Si vous vous êtes trompé, vous pouvez remonter d'un niveau ou de deux niveaux en tapant :
cd .. ou cd ..\..
On peut aussi se faire aider par le système, en tapant juste le début du nom d'un répertoire puis la touche Tabulation : le système complète alors le nom automatiquement.
Ne pas hésiter à taper souvent la commande dir pour voir les fichiers et répertoires présents dans le répertoire courant.

Je n'arrive pas à utiliser l'invite de commande, j'ai donc utilisé Windows Power Shell.

Mais SET PATH et %PATH% ne fonctionnent pas.

Si vous voulez utiliser Windows Power Shell, il faut remplacer la commande
SET PATH="C:\......\bin";%PATH%
par la commande
$env:path = "C:\......\bin" + ";" + $env:path

Un étudiant a écrit :

quand j'accède à la javadoc via le site il ne trouve pas les différents liens par contre quand je lance la page relative à la javadoc depuis le dossier userdoc, tous les liens sont trouvé et ca fonctionne parfaitement.

Il est normal que tout fonctionne bien à partir du dossier où sont les fichiers.

Ce que l'on souhaite, c'est que cela fonctionne pour tous les utilisateurs d'internet ; et ils n'ont pas accès à vos fichiers ...

C'est pourquoi il faut donner au serveur web (qui représente ici les utilisateurs externes) le droit de lire vos fichiers : r pour les fichiers et rx pour les répertoires.

Bonjour, comment fait on quand nous n'avons que Mac ?

MacOS :

Vous avez de la chance : vous allez pouvoir vous entraîner facilement à utiliser les commandes Linux puisque ce sont les mêmes sous MacOS !

Pour vous rassurer, vous pouvez lire ça .

Par contre, depuis que le JDK est incorporé dans BlueJ, il faut effectuer aussi sous MacOS une procédure similaire à celle indiquée ci-dessu pour DOS/Windows.

1) Déterminer le chemin d'accès d'installation du JDK :
- si vous le connaissez, passez directement à l'étape 2)
- en général, /Applications/BlueJ.app/Contents/JDK/Home
- sinon, taper find / -name JDK |& grep JDK pour le découvrir

2) Taper la commande :
export JAVA_HOME=/Applications/BlueJ.app/Contents/JDK/Home
ou, si vous vous utilisez un autre shell, la commande :
set JAVA_HOME /Applications/BlueJ.app/Contents/JDK/Home
en utilisant le chemin trouvé au point précédent, ce qui aura pour effet de rendre accessible notamment la commande javadoc
Pour vérifier que la commande précédente a bien fonctionné, vous pouvez taper la commande set et vous devez voir affichée la variable JAVA_HOME que vous venez d'ajouter avec sa bonne valeur.
Pour vérifier que vous avez utilisé le bon chemin d'accès, vous pouvez taper la commande javadoc et vous ne devez plus voir affiché que cette commande n'est pas reconnue.

2bis) Si javadoc n'est toujours pas reconnue, vous pouvez essayer la commande :
PATH=/Applications/BlueJ.app/Contents/JDK/Home/bin:$PATH
ou, si vous vous utilisez un autre shell, la commande :
set PATH /Applications/BlueJ.app/Contents/JDK/Home/bin:$PATH

3) Pour ne pas avoir refaire cette manipulation à chaque fois qu'on rouvre la fenêtre Terminal, il peut être agréable de la stocker dans un fichier script (en général, .zshrc à la racine du compte ; le créer s'il n'existe pas déjà) qui devra contenir la commande ci-dessus. La commande sera alors automatiquement exécutée dès l'ouverture de la fenêtre Terminal.

La commande cd sous Unix, Linux ou MacOS (Terminal)

Si vous êtes dans un répertoire très différent de celui de votre projet, il suffit de taper :
cd ~
pour revenir à la racine de votre compte.
Pour revenir à la racine de toute la hiérarchie de fichiers, on peut taper :
cd /
Si vous êtes dans la bonne branche de votre hiérarchie de fichiers, il suffit de taper :
cd Rep ou cd Rep/Sous
pour aller dans le répertoire Rep ou le sous-répertoire Sous du répertoire Rep.
Si vous vous êtes trompé, vous pouvez remonter d'un niveau ou de deux niveaux en tapant :
cd .. ou cd ../..
On peut aussi se faire aider par le système, en tapant juste le début du nom d'un répertoire puis la touche Tabulation : le système complète alors le nom automatiquement.
Ne pas hésiter à taper souvent la commande ls pour voir les fichiers et répertoires présents dans le répertoire courant.

Bonjour monsieur,

Je suis sur Mac à présent et j'essaye de générer la javadoc en copiant/collant ce que vous avez donné dans le terminal mais cela ne fonctionne pas et voici la capture d'écran du terminal:

Le message d'erreur me paraît clair : Fichiers *.java non trouvés.

Vous n'êtes donc pas dans le bon répertoire.
Utilisez les commandes linux habituelles pour changer de répertoire courant et pour lister les fichiers présents.

Bonjour Monsieur,

J'ai plusieurs problèmes : un premier problème concernant les commandes de génération des javadocs : userdoc et progdoc sur windows que j'ai avec mon ordinateur personnel, il est peut-être possible que ma version de windows ne permette pas cela, ou du moins pas avec les commandes que vous avez données.

Puis un second beaucoup plus important qui est certainement lié à la génération de la progdoc et de la userdoc puisque l'accès à mon site se faisait correctement avant (avant la génération des javadocs) et ne se fait désormais plus. En effet, sur ma session de l'école en utilisant un terminal Linux, les lignes de commandes pour générer les docs m'ont renvoyé 39 warnings et 1 error pour la progdoc, puis 36 warnings et 1 error pour la userdoc. J'ai pourtant bien exécuté les commandes en étant dans le répertoire du projet_zuul, peut-être est-ce dû au fait qu'il y ait toujours comme sous-répertoire la première javadoc générée qui comporte des fichiers de même nom ? Vous trouverez ci-joint une capture d'écran de mon terminal. Merci de m'orienter dans la démarche à suivre pour pouvoir résoudre ce problème qui m'inquiète.

Cordialement, Andrea PANCRAZI.

Il n'est pas indispensable de corriger les warnings (bien qu'ils vous signalent que votre javadoc est incomplète).

Par contre, il est indispensable de corriger les erreurs.

Dans votre cas ligne 28, vous avez écrit : @param gameEngine The GameEngine object implementing the game logic.
alors que votre paramètre s'appelle sans doute pGameEngine

Avec les caractères accentués :

Pour ceux que ça intéresse s'il y a des problèmes avec les accents dans les javadocs il suffit d'ajouter

-encoding utf8 -docencoding utf8 -charset utf8

ce qui donne :

javadoc -d userdoc -author -version -encoding utf8 -docencoding utf8 -charset utf8 *.java
javadoc -d progdoc -author -version -encoding utf8 -docencoding utf8 -charset utf8 -private -linksource *.java

Merci beaucoup pour cette contribution qui peut aider beaucoup d'étudiants.

On peut peut-être ajouter que les Préférences de Firefox doivent parfois être modifiées pour prendre en compte les caractères Unicode.